기술 문서 3단계 훈련 가이드
이 문서의 목적
규격서·API 명세·기술 문서를 읽을 때 그 자리에서 바로 적용할 수 있는 3단계 훈련과 체크리스트입니다. 왜 이런 방식이 필요했는지, 실제로 어떻게 적용했는지는 규격서의 빈 칸 읽기에 있습니다.
전체 그림
1단계 쓰면서 읽기 → 정보를 눈으로만 지나치지 않는다
2단계 다음을 예측하기 → 저자의 의도와 구조를 따라간다
3단계 점을 선으로 잇기 → 개별 API를 흐름과 구조로 확장한다 ★ 핵심
3단계가 목표이고 1·2단계는 3단계를 하기 위한 준비입니다.
1단계. 쓰면서 읽기 (Active Output Reading)
눈으로만 훑으면 “읽었다”는 느낌만 남습니다. 손과 입을 쓰면 이해하지 못한 지점이 드러납니다.
적용 방법
- 핵심 키워드, 모르는 개념은 즉시 옆에 타이핑하거나 적으면서 읽는다.
- 중요한 흐름은 소리 내어 한 문장으로 설명해 본다. 막히면 그곳이 이해 못 한 곳이다.
쓰는 형식 (예시)
[오퍼레이션] NFListRetrieval
호출 주체: ? ← 모르면 물음표로 남긴다
응답: UriList (프로필 아님)
❓ 왜 URI만?
TIP
물음표를 남기는 것이 요점입니다. 모르는 것을 모르는 채로 표시해 두면 3단계에서 질문 목록이 됩니다.
2단계. 다음을 예측하기 (Context & Build-up Prediction)
문서 구조는 저자가 정한 논리의 순서입니다. 그 순서를 이유까지 읽으면 규격이 암시하는 의도가 보입니다.
적용 방법
- 목차를 볼 때: “왜 이 순서일까?”
- 한 절을 읽기 전에: “다음에 무엇이 나올까?” 를 먼저 적고, 읽은 뒤 맞았는지 비교한다.
- 틀렸다면 내가 놓친 전제가 무엇인지 적는다.
질문 목록
| 시점 | 질문 |
|---|---|
| 목차를 볼 때 | 이 순서로 배치한 이유는? 앞 절이 뒤 절의 전제인가? |
| 절을 읽기 전 | 이 절에서 해결하려는 문제는? 어떤 필드가 나올 것 같은가? |
| 절을 읽은 후 | 내 예측과 달랐던 부분은? 그 차이가 알려 주는 것은? |
3단계. 점을 선으로 잇기 (Systems Connection) ★
규격서는 API를 개별로 설명합니다. 관계는 문단 순서로 암시되거나 언급이 없습니다. 이 단계가 그 빈 칸을 채웁니다.
핵심 질문 5개
| # | 질문 | 찾는 것 |
|---|---|---|
| 1 | 이 API를 호출하기 전에 있어야 하는 상태·데이터는? | 선행 조건 (누가 먼저 무엇을 해 두어야 하나) |
| 2 | 이 응답을 받은 쪽은 다음에 무엇을 하나? | 후속 호출 (응답이 어디로 흘러가나) |
| 3 | 이미 있는 API로 안 되는 이유는? | 이 API가 존재하는 이유 ← 시니어가 던진 바로 그 질문 |
| 4 | 어떤 규모·지연·경계 같은 제약이 이 설계를 강제했나? | 숨은 제약 (양, 속도, 망 경계) |
| 5 | 비슷한 것들 중 이것만 다른 점은? | 비대칭 (허용 범위, 필드 유무의 차이) |
그리는 법
- 점들을 화살표로 잇는 시퀀스 다이어그램 또는 데이터 흐름도를 직접 그린다.
- 규격에 없는 화살표는 점선으로 그리고
?를 붙인다.
AMF ──GET──▶ NSSF ──(nrfId)──▶ AMF ──GET──▶ NRF ──▶ SMF 목록
│
└ ❓ 왜 SMF를 직접 안 주고 NRF 주소를 줄까?
추론은 반드시 태그를 붙인다
| 태그 | 의미 |
|---|---|
| 🟢 명시 | 규격에 직접 적혀 있음 |
| 🟡 암시 | 순서·구조에서 읽힘 |
| 🟠 추론 | 내 가설, 확인 전 |
| 🔵 검증됨 | 규격·동작으로 확인함 |
🟠를 🔵로 바꾸는 작업까지 해야 3단계가 끝납니다. 추론만 하고 검증하지 않으면 그럴듯한 소설이 됩니다.
📋 훈련 체크리스트
문서 하나를 읽을 때마다 아래를 체크합니다.
1단계
- 읽으면서 핵심 흐름을 옆에 타이핑·메모했다
- 모르는 부분을
❓로 남겨 두었다 - 중요한 흐름 하나를 소리 내어 설명해 보았다
2단계
- 목차를 보고 “왜 이 순서인가”를 한 번 적어 보았다
- 절을 읽기 전에 다음 내용을 예측하고, 읽은 뒤 맞았는지 비교했다
3단계
- 핵심 질문 5개 중 3번(이미 있는 API로 안 되는 이유) 을 최소 하나의 API에 던져 보았다
- 서로 다른 API 두 개 이상을 조합해 새로운 흐름을 그려 보았다
- 규격에 없는 관계에 🟠 태그를 붙였다
- 🟠 가설 중 하나를 규격 원문으로 검증했다 (어긋나면 가설을 고쳤다)
흔한 실수
| 실수 | 대신 |
|---|---|
| 추론한 것을 규격에 있는 것처럼 정리한다 | 태그로 출처를 구분한다 |
| 질문만 던지고 답을 확인하지 않는다 | 🟠 항목마다 검증 체크리스트를 둔다 |
| 가설이 틀리면 버린다 | 어긋난 지점이 규격의 숨은 조건을 알려 주므로 가설을 고친다 |
| 한 API만 깊이 본다 | 비슷한 API들을 나란히 놓고 차이를 본다 |
다른 문서에도 쓸 수 있는가
3GPP에서 나온 방법이지만 개별 API/함수가 따로 설명되는 문서라면 모두 적용됩니다.
- RFC, 프로토콜 명세 (메시지 하나하나는 설명하지만 세션 전체 흐름은 흩어져 있음)
- 벤더 API 레퍼런스 (엔드포인트별 설명)
- 프레임워크 공식 문서의 레퍼런스 파트